<!-- HTML header for doxygen 1.9.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>CMSIS-RTOS2: Safety Classes</title>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="tabs.js"></script>
<script type="text/javascript" src="footer.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/javascript" src="darkmode_toggle.js"></script>
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
<link href="extra_navtree.css" rel="stylesheet" type="text/css"/>
<link href="extra_search.css" rel="stylesheet" type="text/css"/>
<link href="extra_tabs.css" rel="stylesheet" type="text/css"/>
<link href="version.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../version.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 55px;">
  <td id="projectlogo" style="padding: 1.5em;"><img alt="Logo" src="cmsis_logo_white_small.png"/></td>
  <td style="padding-left: 1em; padding-bottom: 1em;padding-top: 1em;">
   <div id="projectname">CMSIS-RTOS2
   &#160;<span id="projectnumber"><script type="text/javascript">
     <!--
     writeHeader.call(this);
     writeVersionDropdown.call(this, "CMSIS-RTOS2");
     //-->
    </script>
   </span>
   </div>
   <div id="projectbrief">Real-Time Operating System API</div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
  <!--END !PROJECT_NAME-->
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<div id="CMSISnav" class="tabs1">
  <ul class="tablist">
    <script type="text/javascript">
      writeComponentTabs.call(this);
    </script>
  </ul>
</div>
<script type="text/javascript">
  writeSubComponentTabs.call(this);
</script>
<!-- Generated by Doxygen 1.9.6 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('rtos_process_isolation_safety_class.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Safety Classes </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="el" href="rtos_process_isolation_mpu.html#rtos_process_isolation_mpu_objects">RTOS Objects and MPU Protection</a> explains that MPU Protected Zones do not provide full access protection to RTOS objects accessed via CMSIS-RTOS2 API. The concept of a safety class fills this gap.</p>
<p>Every RTOS object, including thread is assigned with a numeric safety class value. A thread cannot modify an RTOS object if its safety class value is higher than the safety class value of the thread. For example, it is not possible to change the priority or suspend a thread that has a higher safety class value than the thread that is currently executed.</p>
<p><b>Function references</b></p>
<ul>
<li>Following functions and macros are used explicitly for managing safety classes:<ul>
<li><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga604fce4f5205f92c347eb62fcc216861">osSafetyClass</a> :  Safety class value in attribute bit field format.  </li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga1bfbef7da94ed4147d231e8d6eeb5f3e">osThreadGetClass</a> :  Get safety class of a thread.  </li>
<li><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga7abd2d95425d9e02672778b3464b2eaa">osSafetyWithSameClass</a> :  Objects with same safety class.  </li>
<li><a class="el" href="group__CMSIS__RTOS__Definitions.html#ga8c77ee126b9215425fc004ee13cdc6de">osSafetyWithLowerClass</a> :  Objects with lower safety class.  </li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gac7e3b012c15c55bda68e0dd96ad9cd72">osKernelProtect</a> :  Protect the RTOS Kernel scheduler access.  </li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gadadb56627094dbb07f6aeddf7d713fd9">osThreadSuspendClass</a> :  Suspend execution of threads for specified safety classes.  </li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gadd0a06b459925eb5cdeab67b380a3970">osThreadResumeClass</a> :  Resume execution of threads for specified safety classes.  </li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga2065364d1bc805a40e749430377df1e1">osKernelDestroyClass</a> :  Destroy objects for specified safety classes.  </li>
</ul>
</li>
<li>CMSIS-RTOS2 API functions that support safety class assignment when creating RTOS objects are listed in <a class="el" href="rtos_process_isolation_safety_class.html#rtos_process_isolation_safety_class_assign">Assign Safety Class to an RTOS Object</a>.</li>
<li>CMSIS-RTOS2 API functions that verify safety class assignment before execution are listed in <a class="el" href="rtos_process_isolation_safety_class.html#rtos_process_isolation_safety_class_error">Handle Object Access Violation</a> lists.</li>
</ul>
<h1><a class="anchor" id="rtos_process_isolation_safety_class_assign"></a>
Assign Safety Class to an RTOS Object</h1>
<p>It is possible to create any objects regardless of the safety class after the kernel initialize with <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae818f6611d25ba3140bede410a52d659">osKernelInitialize</a>, but before the kernel is started with <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga9ae2cc00f0d89d7b6a307bba942b5221">osKernelStart</a>. This allows to setup a system before actually starting the RTOS kernel.</p>
<p>Threads of a higher safety class can create RTOS objects that belong to a lower or same safety class. For the object types listed below, the <em>attr_bits</em> can have an optional safety class value that is assigned when the RTOS object is created with the <em><em>os&lt;Object&gt;New</em></em> function. The macro <a class="el" href="group__CMSIS__RTOS__Definitions.html#ga604fce4f5205f92c347eb62fcc216861">osSafetyClass</a> encodes the value for the <em>attr_bits</em> field in the attr struct. For example:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code hl_struct" href="group__CMSIS__RTOS__EventFlags.html#structosEventFlagsAttr__t" title="Attributes structure for event flags.">osEventFlagsAttr_t</a> evt_flags_attr = {</div>
<div class="line">  .<a class="code hl_variable" href="group__CMSIS__RTOS__EventFlags.html#a6e93b49cb79c12f768d72580c7731f30" title="attribute bits">attr_bits</a> = <a class="code hl_define" href="group__CMSIS__RTOS__Definitions.html#ga604fce4f5205f92c347eb62fcc216861" title="Safety class value in attribute bit field format.">osSafetyClass</a>(SAFETY_CLASS_SAFE_MODE_OPERATION)</div>
<div class="line">};</div>
<div class="line"><a class="code hl_typedef" href="group__CMSIS__RTOS__EventFlags.html#gafdbab933146d6d81d7cca7287e267a50">osEventFlagsId_t</a> evt_flags;</div>
<div class="line">evt_flags = <a class="code hl_function" href="group__CMSIS__RTOS__EventFlags.html#gab14b1caeb12ffa42cce1bfe889cd07df" title="Create and Initialize an Event Flags object.">osEventFlagsNew</a>(&amp;evt_flags_attr);</div>
</div><!-- fragment --><p>The following object types support safety class assignment when creating an object with corresponding <em>os&lt;Object&gt;New</em> function:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#structosThreadAttr__t">osThreadAttr_t</a>  Attributes structure for thread.   Used in the <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#structosEventFlagsAttr__t">osEventFlagsAttr_t</a>  Attributes structure for event flags.   Used in the <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#structosTimerAttr__t">osTimerAttr_t</a>  Attributes structure for timer.   Used in the <a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gad4e7f785c5f700a509f55a3bf6a62bec">osTimerNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#structosMutexAttr__t">osMutexAttr_t</a>  Attributes structure for mutex.   Used in the <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#structosSemaphoreAttr__t">osSemaphoreAttr_t</a>  Attributes structure for semaphore.   Used in the <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga2a39806ace781a0008a4374ca701b14a">osSemaphoreNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#structosMemoryPoolAttr__t">osMemoryPoolAttr_t</a>  Attributes structure for memory pool.   Used in the <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga497ced5d72dc5cd405c4c418516220dc">osMemoryPoolNew</a> function.</li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#structosMessageQueueAttr__t">osMessageQueueAttr_t</a>  Attributes structure for message queue.   Used in the <a class="el" href="group__CMSIS__RTOS__Message.html#ga24e895a00f9d484db33aaf784c57bfed">osMessageQueueNew</a> function.</li>
</ul>
<p>If safety class is not provided when creating the RTOS object then it inherits the safety class of the current running thread that creates the object. If the object is created before kernel is started and no safety class is provided, then it receives default safety class 0. This simplifies integration of third-party code that can be classified as non-safety critical.</p>
<h1><a class="anchor" id="rtos_process_isolation_safety_class_error"></a>
Handle Object Access Violation</h1>
<p>RTOS API call returns error code <a class="el" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813ea7379a8ce2e513723390bb01d2efeb981">osErrorSafetyClass</a> if the requested object manipulation cannot be performed because the target object has higher safety class than the safety class of the running thread. For example:</p>
<div class="fragment"><div class="line">status = <a class="code hl_function" href="group__CMSIS__RTOS__EventFlags.html#ga33b71d14cecf90b4e72639dd19f23a5e" title="Set the specified Event Flags.">osEventFlagsSet</a>(evt_flags, 1);</div>
<div class="line"><span class="keywordflow">if</span> (status == <a class="code hl_enumvalue" href="group__CMSIS__RTOS__Definitions.html#gga6c0dbe6069e4e7f47bb4cd32ae2b813ea7379a8ce2e513723390bb01d2efeb981" title="Operation denied because of safety class violation.">osErrorSafetyClass</a>)</div>
<div class="line">{</div>
<div class="line">  <span class="comment">//handle the safety class error</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>Following functions compare the safety class of the running thread with the safety class of the target object.</p>
<p>In <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html">Kernel Information and Control</a> functions:</p>
<p>Comparison is done with safety class configured with <a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gac7e3b012c15c55bda68e0dd96ad9cd72">osKernelProtect</a></p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga948609ee930d9b38336b9e1c2a4dfe12">osKernelLock</a></li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae7d0a71b9586cbbb49fcbdf6a04f0289">osKernelRestoreLock</a></li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gae26683e1606ec633354a2876c68f0c1f">osKernelSuspend</a></li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#gac7e3b012c15c55bda68e0dd96ad9cd72">osKernelProtect</a></li>
<li><a class="el" href="group__CMSIS__RTOS__KernelCtrl.html#ga2065364d1bc805a40e749430377df1e1">osKernelDestroyClass</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html">Thread Management</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga48d68b8666d99d28fa646ee1d2182b8f">osThreadNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga861a420fb2d643115b06622903fb3bfb">osThreadSetPriority</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaa9de419d0152bf77e9bbcd1f369fb990">osThreadSuspend</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga3dbad90eff394b02de76a452c84c5d80">osThreadResume</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gaaad14cd9547341ea8109dc4e8540f1dc">osThreadDetach</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga3fca90fb0679afeb968aa8c3d5874487">osThreadJoin</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#ga2f8ba6dba6e9c065a6e236ffd410d74a">osThreadTerminate</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gadadb56627094dbb07f6aeddf7d713fd9">osThreadSuspendClass</a></li>
<li><a class="el" href="group__CMSIS__RTOS__ThreadMgmt.html#gadd0a06b459925eb5cdeab67b380a3970">osThreadResumeClass</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html">Thread Flags</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__ThreadFlagsMgmt.html#ga6f89ef9caded1d9963c7b12b0f6412c9">osThreadFlagsSet</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__EventFlags.html">Event Flags</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#gab14b1caeb12ffa42cce1bfe889cd07df">osEventFlagsNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga33b71d14cecf90b4e72639dd19f23a5e">osEventFlagsSet</a></li>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga93bf258ca0007c6641fbe8e4f2b8a1e5">osEventFlagsClear</a></li>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga52acb34a8322e58020227344fe662b4e">osEventFlagsWait</a></li>
<li><a class="el" href="group__CMSIS__RTOS__EventFlags.html#ga7c4acf2fb0d506ec82905dee53fb5435">osEventFlagsDelete</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__TimerMgmt.html">Timer Management</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gad4e7f785c5f700a509f55a3bf6a62bec">osTimerNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gab6ee2859ea657641b7adfac599b8121d">osTimerStart</a></li>
<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gabd7a89356da7717293eb0bc5d87b8ac9">osTimerStop</a></li>
<li><a class="el" href="group__CMSIS__RTOS__TimerMgmt.html#gad0001dd74721ab461789324806db2453">osTimerDelete</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__MutexMgmt.html">Mutex Management</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gab90920022ab944296821368ef6bb52f8">osMutexNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabc54686ea0fc281823b1763422d2a924">osMutexAcquire</a></li>
<li><a class="el" href="group__CMSIS__RTOS__MutexMgmt.html#gabee73ad227ba4587d3db12ef9bd582bc">osMutexDelete</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html">Semaphores</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga2a39806ace781a0008a4374ca701b14a">osSemaphoreNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga7e94c8b242a0c81f2cc79ec22895c87b">osSemaphoreAcquire</a></li>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga0abcee1b5449d7a6928fb9248c690bb6">osSemaphoreRelease</a></li>
<li><a class="el" href="group__CMSIS__RTOS__SemaphoreMgmt.html#ga81258ce9c67fa89f07cc49d2e136cd88">osSemaphoreDelete</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__PoolMgmt.html">Memory Pool</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga497ced5d72dc5cd405c4c418516220dc">osMemoryPoolNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga8ead54e99ccb8f112356c88f99d38fbe">osMemoryPoolAlloc</a></li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#gabb4f4560daa6d1f8c8789082ee186d16">osMemoryPoolFree</a></li>
<li><a class="el" href="group__CMSIS__RTOS__PoolMgmt.html#ga8c39e7e5cd2b9eda907466808e59d62e">osMemoryPoolDelete</a></li>
</ul>
<p>In <a class="el" href="group__CMSIS__RTOS__Message.html">Message Queue</a> functions:</p>
<ul>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#ga24e895a00f9d484db33aaf784c57bfed">osMessageQueueNew</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#gaa515fc8b956f721a8f72b2c505813bfc">osMessageQueuePut</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#gad90d4959466a7a65105061da8256ab9e">osMessageQueueGet</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#gac6dce7f9ad132d266292c2e979d861b4">osMessageQueueReset</a></li>
<li><a class="el" href="group__CMSIS__RTOS__Message.html#gaba987f665444e0d83fa6a3a68bc72abe">osMessageQueueDelete</a> </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">
      <script type="text/javascript">
        <!--
        writeFooter.call(this);
        //-->
      </script> 
    </li>
  </ul>
</div>
</body>
</html>
